chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

aramos-adobe · 2025-09-18T04:38:33Z

Description

Creates AI-generated migration documentation to analyze component differences to guide SWC migration to S2, with human vetting. The documentation serves as a bridge between the migrated Spectrum 2 CSS work and the corresponding web components, in order to help engineers understand what needs to be implemented, updated, or aligned between the two systems to guide the development of 2nd generation web components.

This batch is for the barebones components:

Avatar
Opacity checkerboard
Swatch + Swatch group
Thumbnail

Motivation and context

Clear development roadmap: Provides comprehensive feature gap analysis for building 2nd generation web components
Implementation requirements: Identifies all features and capabilities that need to be implemented to match Spectrum 2 CSS and design specs
Breaking change transparency: Establishes implementation requirements and design changes that may lead to breaking changes and/or API changes for the next major version
Adoption planning: Enables developers and consuming teams to plan for 2nd gen web component adoption and understand migration effort required

Related issue(s)

SWC-1221

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
~~I have added automated tests to cover my changes.~~
~~I have included a well-written changeset if my change needs to be published.~~
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
~~Includes thoughtfully written changeset if changes suggested include patch, minor, or major features~~
~~Automated tests cover all use cases and follow best practices for writing~~
~~Validated on all supported browsers~~
~~All VRTs are approved before the author can update Golden Hash~~

Documentation Quality

All files follow template structure with proper collapsible sections
CSS => SWC mapping tables use correct status values
Summary sections are concise and actionable
No broken markdown syntax

Cross-Reference Accuracy

CSS selectors match actual metadata.json files
SWC attributes match actual TypeScript source files
DOM structure comparisons match template files
Implementation gaps are complete and accurate

changeset-bot · 2025-09-18T04:38:37Z

⚠️ No Changeset found

Latest commit: d2af5b1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-09-18T04:40:28Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5740

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-09-18T04:43:30Z

Tachometer results

Currently, no packages are changed by this PR...

rise-erpelding

Left some comments! We'll definitely want to fill in the Resources sections here, plus review some of the callouts that the docs are making for accuracy!

migration-roadmap/avatar.md

migration-roadmap/swatch.md

migration-roadmap/swatch-group.md

migration-roadmap/thumbnail.md

migration-roadmap/avatar.md

marissahuysentruyt · 2025-09-25T17:39:28Z

migration-roadmap/avatar.md

+```html
+<!-- With link -->
+<a id="link" class="link" href="[href]">
+    <img class="image" alt="[label]" src="[src]" />


oh I love how this showcases where the props go!

migration-roadmap/avatar.md

marissahuysentruyt · 2025-09-25T17:48:14Z

migration-roadmap/avatar.md

+
+## Summary of changes
+
+### CSS => SWC implementation gaps


oh! There's a follow up ticket for avatar with some newly added default gradient background support. Should we call out that there's more to this component that isn't supported by CSS yet either?

Just thinking out loud- when would that work be done? Separately from the SWC migration to S2? Like a follow up once avatar has migrated?

Oh dang, that's tough. I'm tempted to call it "out of scope" for now since it wasn't in place when we first migrated the component. Do you think we're likely to miss it if we do that though?

I don't think it hurts to include information about variants that we didn't implement in CSS, and I'm not sure what the exact order of implementation would be, but I would guess that we might do a single pass to bring our existing CSS over, then go back and address the other variants later, so it might not be absolutely necessary to include for the "first pass" migration.

We do have a ticket for those additional variants: CSS-1236. If that ends up happening in CSS before we migrate, we should come back and note it in these docs. But if we address it in SWC, I think we'll be ok.

I'm also hoping/assuming that we'll do some kind of design review before shipping anything so that's another fallback for missing variants to be called out!

migration-roadmap/opacity-checkerboard.md

migration-roadmap/swatch-group.md

migration-roadmap/thumbnail.md

migration-roadmap/avatar.md

rise-erpelding · 2025-09-26T14:04:43Z

migration-roadmap/opacity-checkerboard.md

+
+- [CSS migration](https://github.com/adobe/spectrum-css/pull/3394)
+- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-opacity-checkerboard--docs)
+- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorslider--docs) (not a standalone component, but styles are used by the color slider)


not a standalone component, but styles are used by the color slider

Love this clarification, will be borrowing this for other components if it comes up.

migration-roadmap/avatar.md

migration-roadmap/swatch.md

migration-roadmap/swatch-group.md

migration-roadmap/thumbnail.md

migration-roadmap/avatar.md

rise-erpelding · 2025-10-03T13:32:39Z

migration-roadmap/avatar.md

+
+## Summary of changes
+
+### CSS => SWC implementation gaps


I don't think it hurts to include information about variants that we didn't implement in CSS, and I'm not sure what the exact order of implementation would be, but I would guess that we might do a single pass to bring our existing CSS over, then go back and address the other variants later, so it might not be absolutely necessary to include for the "first pass" migration.

We do have a ticket for those additional variants: CSS-1236. If that ends up happening in CSS before we migrate, we should come back and note it in these docs. But if we address it in SWC, I think we'll be ok.

I'm also hoping/assuming that we'll do some kind of design review before shipping anything so that's another fallback for missing variants to be called out!

migration-roadmap/swatch.md

rise-erpelding · 2025-10-03T13:52:54Z

migration-roadmap/swatch.md

+- `rounding` (string) - Corner rounding: 'none', 'full'
+- `selected` (boolean) - Whether the swatch is selected
+- `shape` (string) - Shape variant: 'rectangle'
+- `size` (string) - Size: 'xs', 's', 'm', 'l'


Is it maybe because it's using a size mixin? I've noticed if the types aren't defined within the file (if they're imported) those don't get picked up either.

migration-roadmap/thumbnail.md

marissahuysentruyt

Looks like most of my initial comments have been addressed, except for the ones in thumbnail. @rise-erpelding did an excellent job of documenting those via suggestions, so I won't clutter the PR with more comments on the same things!

aramos-adobe requested a review from a team as a code owner September 18, 2025 04:38

aramos-adobe changed the title ~~Aramos-adobe/swc1221-component-analysis-docs~~ chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail Sep 18, 2025

aramos-adobe self-assigned this Sep 18, 2025

aramos-adobe requested review from cdransf, rise-erpelding and marissahuysentruyt September 18, 2025 04:40

aramos-adobe added ready-for-review Documentation labels Sep 18, 2025

rise-erpelding requested changes Sep 19, 2025

View reviewed changes

marissahuysentruyt self-assigned this Sep 23, 2025

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch 4 times, most recently from 152b6af to c5f8345 Compare September 24, 2025 20:31

marissahuysentruyt reviewed Sep 25, 2025

View reviewed changes

rise-erpelding reviewed Sep 26, 2025

View reviewed changes

marissahuysentruyt assigned castastrophe and unassigned marissahuysentruyt Sep 29, 2025

rise-erpelding force-pushed the 2nd-gen-component-analysis branch from 1c7d103 to ab5ae6a Compare October 1, 2025 21:23

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch 2 times, most recently from 088c63c to ee5fdd5 Compare October 2, 2025 18:11

castastrophe requested review from rise-erpelding and marissahuysentruyt October 2, 2025 18:12

rise-erpelding reviewed Oct 3, 2025

View reviewed changes

rise-erpelding force-pushed the 2nd-gen-component-analysis branch from 9e7a40d to ff74e36 Compare October 6, 2025 15:13

marissahuysentruyt reviewed Oct 7, 2025

View reviewed changes

chore(docs): barebones component migration analysis

f9c8a99

castastrophe and others added 3 commits October 8, 2025 11:33

chore: apply code review feedback

c11dd54

chore: apply code review feedback

b1db59e

docs(avatar,thumbnail,swatch): pr suggestions

d2af5b1

rise-erpelding force-pushed the aramos-adobe/swc1221-component-analysis-docs branch from d920c46 to d2af5b1 Compare October 8, 2025 16:34

rise-erpelding approved these changes Oct 8, 2025

View reviewed changes

marissahuysentruyt approved these changes Oct 8, 2025

View reviewed changes

rise-erpelding merged commit 169a999 into 2nd-gen-component-analysis Oct 8, 2025
16 of 22 checks passed

rise-erpelding deleted the aramos-adobe/swc1221-component-analysis-docs branch October 8, 2025 16:45

chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

Conversation

aramos-adobe commented Sep 18, 2025

Description

Motivation and context

Related issue(s)

Author's checklist

Reviewer's checklist

Documentation Quality

Cross-Reference Accuracy

Uh oh!

changeset-bot bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Sep 18, 2025

Tachometer results

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marissahuysentruyt Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marissahuysentruyt Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

castastrophe Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

rise-erpelding Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rise-erpelding Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rise-erpelding Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rise-erpelding Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

changeset-bot bot commented Sep 18, 2025 •

edited

Loading

github-actions bot commented Sep 18, 2025 •

edited

Loading